MAP

The MAP function returns a reference to the MapProjection object. Use the returned reference to manipulate the graphic after creation by changing properties or calling methods.

Arguments

Projection

A string giving the name of the map projection. Available projections and their allowed parameters include:

#	Name	Allowed Map Parameters	Notes
100	Geographic	CENTER_LONGITUDE	No projection.
101	UTM	SEMIMAJOR_AXIS, SEMIMINOR_AXIS, CENTER_LONGITUDE, CENTER_LATITUDE, ZONE	All ellipsoids; cylindrical; conformal; scale is reduced along the central longitude (MERCATOR_SCALE=0.9996).
102	State Plane	ZONE	"Clarke 1866" or "GRS 1980" ellipsoid; uses either Transverse Mercator, Lambert Conformal Conic, or Hotine Oblique Mercator.
103	Albers Equal Area	SEMIMAJOR_AXIS, SEMIMINOR_AXIS, STANDARD_PAR1, STANDARD_PAR2, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING	All ellipsoids; conic; equal-area; scale is true along the two standard parallels.
104	Lambert Conformal Conic	SEMIMAJOR_AXIS, SEMIMINOR_AXIS, STANDARD_PAR1, STANDARD_PAR2, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING	All ellipsoids; conformal; scale is true along the two standard parallels.
105	Mercator	SEMIMAJOR_AXIS, SEMIMINOR_AXIS, CENTER_LONGITUDE, TRUE_SCALE_LATITUDE, FALSE_EASTING, FALSE_NORTHING	All ellipsoids; cylindrical; conformal; scale is true along the true scale latitudes.
106	Polar Stereographic	SEMIMAJOR_AXIS, SEMIMINOR_AXIS, CENTER_LONGITUDE, TRUE_SCALE_LATITUDE, FALSE_EASTING, FALSE_NORTHING	All ellipsoids; azimuthal; conformal; scale is true along the true scale latitude.
107	Polyconic	SEMIMAJOR_AXIS, SEMIMINOR_AXIS, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING	All ellipsoids; neither conformal nor equal-area; scale is true along all parallels and along the central meridian.
108	Equidistant Conic	SEMIMAJOR_AXIS, SEMIMINOR_AXIS, STANDARD_PARALLEL, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING	All ellipsoids; equidistant; scale is true along all meridians and along one standard parallel.
208	Equidistant Conic	SEMIMAJOR_AXIS, SEMIMINOR_AXIS, STANDARD_PAR1, STANDARD_PAR2, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING	All ellipsoids; equidistant; scale is true along all meridians and along two standard parallels.
109	Transverse Mercator	SEMIMAJOR_AXIS, SEMIMINOR_AXIS, MERCATOR_SCALE, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING	All ellipsoids; cylindrical; conformal; scale is true (or reduced) along the center longitude.
110	Stereographic	SPHERE_RADIUS, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING	Sphere only; azimuthal; conformal; scale is true at the center; directions from the center are true.
111	Lambert Azimuthal	SEMIMAJOR_AXIS, SEMIMINOR_AXIS, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING	All ellipsoids; azimuthal; equal-area; scale is true at the center; directions from the center are true for spherical and polar ellipsoidal.
112	Azimuthal Equidistant	SPHERE_RADIUS, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING	Sphere only; azimuthal; equidistant; distances measured from the center are true; directions from the center are true; scale is true at the center.
113	Gnomonic	SPHERE_RADIUS, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING	Sphere only; also known as the Gnomic or Central projection; azimuthal and perspective; neither conformal nor equal-area; all great circles are straight lines; scale is true at the center; directions from the center are true.
114	Orthographic	SPHERE_RADIUS, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING	Sphere only; azimuthal; neither conformal nor equal-area; scale is true in the direction of latitude lines for the polar aspect; directions from the center are true.
115	Near Side Perspective	SEMIMAJOR_AXIS, SEMIMINOR_AXIS, HEIGHT, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING	All ellipsoids (default is Sphere); also known as the Vertical Perspective; azimuthal; neither conformal nor equal-area; scale is true at the center; directions from the center are true.
116	Sinusoidal	SPHERE_RADIUS, CENTER_LONGITUDE, FALSE_EASTING, FALSE_NORTHING	Sphere only; pseudocylindrical; equal-area; scale is true along the central meridian and along all parallels.
117	Equirectangular	SPHERE_RADIUS, CENTER_LONGITUDE, TRUE_SCALE_LATITUDE, FALSE_EASTING, FALSE_NORTHING	Sphere only; also known as equidistant cylindrical; neither conformal nor equal-area; scale is true along all meridians and along the true scale latitudes.
118	Miller Cylindrical	SPHERE_RADIUS, CENTER_LONGITUDE, FALSE_EASTING, FALSE_NORTHING	Sphere only; neither conformal nor equal-area; scale is true along the equator.
119	Van der Grinten	SPHERE_RADIUS, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING	Sphere only; neither conformal nor equal-area; scale is true along the equator.
120	Hotine Oblique Mercator	SEMIMAJOR_AXIS, SEMIMINOR_AXIS, MERCATOR_SCALE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING, HOM_LONGITUDE1, HOM_LATITUDE1, HOM_LONGITUDE2, HOM_LATITUDE2	All ellipsoids; cylindrical; conformal; scale is true (or reduced) along the center line. Specified using two lat-lon points.
220	Hotine Oblique Mercator	SEMIMAJOR_AXIS, SEMIMINOR_AXIS, MERCATOR_SCALE, HOM_AZIM_ANGLE, HOM_AZIM_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING	All ellipsoids; cylindrical; conformal; scale is true (or reduced) along the center line. Specified using azimuthal angle and longitude of the center.
121	Robinson	SPHERE_RADIUS, CENTER_LONGITUDE, FALSE_EASTING, FALSE_NORTHING	Sphere only; pseudocylindrical; neither conformal nor equal-area; scale is true along the 38° parallels.
122	Space Oblique Mercator	SEMIMAJOR_AXIS, SEMIMINOR_AXIS, SOM_INCLINATION, SOM_LONGITUDE, FALSE_EASTING, FALSE_NORTHING, SOM_PERIOD, SOM_RATIO, SOM_FLAG	All ellipsoids; modified cylindrical; basically conformal; scale is true along the groundtrack. Specified using inclination, longitude, period, ratio, and flag.
222	Space Oblique Mercator	SEMIMAJOR_AXIS, SEMIMINOR_AXIS, SOM_LANDSAT_NUMBER, SOM_LANDSAT_PATH, FALSE_EASTING, FALSE_NORTHING	All ellipsoids; modified cylindrical; basically conformal; scale is true along the groundtrack. Specified using landsat number and path.
123	Alaska Conformal	SEMIMAJOR_AXIS, SEMIMINOR_AXIS, FALSE_EASTING, FALSE_NORTHING	All ellipsoids; conformal; modified stereographic using complex algebra transformations to reduce scale variations.
124	Interrupted Goode	SPHERE_RADIUS	Sphere only; pseudocylindrical; equal-area; scale is true along the central meridians and along all parallels.
125	Mollweide	SPHERE_RADIUS, CENTER_LONGITUDE, FALSE_EASTING, FALSE_NORTHING	Sphere only; pseudocylindrical; equal-area; scale is true along latitudes 40°44' N and S.
126	Interrupted Mollweide	SPHERE_RADIUS	Sphere only; pseudocylindrical; equal-area; scale is true along the 40°44' parallels.
127	Hammer	SPHERE_RADIUS, CENTER_LONGITUDE, FALSE_EASTING, FALSE_NORTHING	Sphere only; also known as Hammer-Aitoff; based on Lambert Azimuthal; equal-area but not azimuthal; scale is true at the center.
128	Wagner IV	SPHERE_RADIUS, CENTER_LONGITUDE, FALSE_EASTING, FALSE_NORTHING	Sphere only; pseudocylindrical; equal-area; scale is true along the 42°59' parallels.
129	Wagner VII	SPHERE_RADIUS, CENTER_LONGITUDE, FALSE_EASTING, FALSE_NORTHING	Sphere only; modification of the Hammer; equal-area; scale is true at the center.
130	Oblated Equal Area	SPHERE_RADIUS, OEA_SHAPEM, OEA_SHAPEN, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING, OEA_ANGLE	Sphere only; equal-area; lines of constant distortion follow approximately oval or rectangular paths.
131	Integerized Sinusoidal	SPHERE_RADIUS, CENTER_LONGITUDE, FALSE_EASTING, FALSE_NORTHING, IS_ZONES, IS_JUSTIFY	Sphere only; equal-area; same as sinusoidal but with discrete latitude bands.
132	Cylindrical Equal Area	SEMIMAJOR_AXIS, SEMIMINOR_AXIS, CENTER_LONGITUDE, STANDARD_PARALLEL, FALSE_EASTING, FALSE_NORTHING	All ellipsoids; cylindrical; equal-area; scale is true along the standard parallels (special cases: Lambert 0°, Behrmann 30°, Trystan Edwards 37.383°, Peters 44.138°, Gall orthographic 45°, Balthasart 50°.
133	GOES-R	SEMIMAJOR_AXIS, SEMIMINOR_AXIS, CENTER_LONGITUDE, HEIGHT, FALSE_EASTING, FALSE_NORTHING	All ellipsoids (default is GRS 1980); same properties as Near Side Perspective but (x, y) coordinates are in scan-angle radians. Default height is 35786023 meters.

Map Properties

CENTER_LATITUDE

CENTER_LONGITUDE

ELLIPSOID

FALSE_EASTING

FALSE_NORTHING

HEIGHT

HOM_AZIM_ANGLE

HOM_AZIM_LONGITUDE

HOM_LATITUDE1

HOM_LATITUDE2

HOM_LONGITUDE1

HOM_LONGITUDE2

IS_JUSTIFY

IS_ZONES

LIMIT

MERCATOR_SCALE

OEA_ANGLE

OEA_SHAPEM

OEA_SHAPEN

SEMIMAJOR_AXIS

SEMIMINOR_AXIS

SOM_FLAG

SOM_INCLINATION

SOM_LANDSAT_NUMBER

SOM_LANDSAT_PATH

SOM_LONGITUDE

SOM_PERIOD

SOM_RATIO

SPHERE_RADIUS

STANDARD_PAR1

STANDARD_PAR2

STANDARD_PARALLEL

TRUE_SCALE_LATITUDE

ZONE

See MAP_PROJ_INIT for descriptions of these properties.

Map Grid Properties

The following map graticule (grid) properties are available on creation:

BOX_ANTIALIAS

BOX_AXES

BOX_COLOR

BOX_THICK

CLIP

COLOR

FILL_COLOR

FONT_NAME

FONT_SIZE

FONT_STYLE

GRID_LATITUDE

GRID_LONGITUDE

HIDE

HORIZON_COLOR

HORIZON_LINESTYLE

HORIZON_THICK

LABEL_ALIGN

LABEL_ANGLE

LABEL_COLOR

LABEL_FILL_BACKGROUND

LABEL_FILL_COLOR

LABEL_FORMAT

LABEL_POSITION

LABEL_SHOW

LABEL_VALIGN

LATITUDE_MAX

LATITUDE_MIN

LINESTYLE

LONGITUDE_MAX

LONGITUDE_MIN

THICK

TRANSPARENCY

ZVALUE

You may also get or set a property after creation, and the request will automatically be passed down to the MapGrid object. Or, you can use the MAPGRID property to retrieve a reference to the MapGrid, and then get or set properties directly on that object. See the MAPGRID function for a description of these properties.

Keywords

Keywords are applied only during the initial creation of the graphic.

BUFFER

Set this keyword to 1 to direct the graphics to an off-screen buffer instead of creating a window.

CURRENT

Set this keyword to create the graphic in the current window with a new set of axes. If no window exists, a new window is created. The WINDOW's SetCurrent method may be used to set the current window.

Or, set this keyword to an existing IDL Graphic reference to make that window be the current window and direct the new graphic to that window.

Tip: The CURRENT keyword is usually used with the LAYOUT keyword or POSITION property to produce a window which has multiple graphics in different locations.

Tip: For the graphic share the same axes as an existing graphic, use the OVERPLOT keyword instead.

DEVICE

Set this keyword if values are specified in device coordinates (pixels) for the MARGIN and POSITION keywords. (Normalized coordinates are the default for these keywords.)

DIMENSIONS

Set this keyword to a two-element vector of the form [width, height] to specify the window dimensions in pixels. If you do not specify a value for DIMENSIONS, IDL by default uses the values of the IDL_GR_WIN_HEIGHT and IDL_GR_WIN_WIDTH preferences for Windows platforms or the IDL_GR_X_HEIGHT and IDL_GR_X_WIDTH preferences for X Windows systems on UNIX.

Tip: The minimum width is set by the toolbar in the window, usually around 400 pixels. To create a smaller graphics window, use the NO_TOOLBAR keyword.

LAYOUT

Set this keyword to a three-element vector [ncol, nrow, index] that arranges graphics in a grid. The first dimension ncol is the number of columns in the grid, nrow is the number of rows, and index is the grid position at which to place the graphic (starting at element 1). This keyword is ignored if either OVERPLOT or POSITION is specified.

LOCATION

Set this keyword to a two-element vector [X offset, Y offset] giving the window's screen offset in pixels.

MARGIN

Set this keyword to the current graphic’s margin values in the layout specified by the LAYOUT property. Use a scalar value to set the same margin on all sides, or use a four-element vector [left, bottom, right, top] to specify different margins on each side.

By default, margin values are expressed in normalized units ranging from 0.0 to 0.5. If the DEVICE keyword is set, the values are given in device units (pixels).

This keyword is ignored if either OVERPLOT or POSITION is specified.

NO_TOOLBAR

By default the graphics window will have a toolbar containing some common tools such as Print and Save. Set this keyword to remove the toolbar. This keyword has no effect if the window is already created.

Tip: When the toolbar exists, the minimum window width is set to the toolbar's width, usually around 400 pixels. To create a smaller graphics window, use the NO_TOOLBAR keyword.

NODATA

Set this keyword to 1 to create the graphic, but without any data attached to it. The axes and title (if present) are also created and displayed. If the OVERPLOT keyword is specified, axis ranges will not change.

Note: You must still provide valid input arguments. The data range of the input arguments are used to automatically set the range of the axes. The [XYZ]RANGE properties may be used to override these default ranges.

OVERPLOT

Set this keyword to 1 (one) to place the graphic on top of the currently-selected graphic within the current window. The two graphics items will then share the same set of axes. If no current window exists, then this keyword is ignored and a new window is created.

If you have a graphic in another window that is not currently selected, you can also set this keyword to that graphic's reference to overplot on top of that graphic.

Tip: For the graphic to have a new set of axes, use the CURRENT keyword instead.

WIDGETS

By default, when running from the IDL Workbench, the graphics window will use the native widgets for your platform. Set this keyword to instead use IDL widgets for the graphics window. This keyword is ignored when running from the IDL command line, since IDL widgets are always used in that case.

Properties

BACKGROUND_COLOR

Set this property to a string or RGB vector indicating the graphic's background color. The default value is [255, 255, 255] (white). Set this property to a scalar value to remove the background color.

Tip: To set the background color of the entire window, retrieve the window object using the WINDOW property, and set the BACKGROUND_COLOR on the window object.

BACKGROUND_TRANSPARENCY

Set this property to an integer between 0 and 100 giving the percent transparency of the background color. The default is 100 (completely transparent).

Note: If the BACKGROUND_COLOR property is changed, and the current background transparency is 100, then the BACKGROUND_TRANSPARENCY will be automatically set to 0 (opaque) so that you can see the new color.

FONT_COLOR

Set this property to a string or RGB vector that specifies the color of the title (if present). The default value is "black".

FONT_NAME

Set this property equal to a string specifying the IDL or system font for the title (if present). The default value is "DejaVuSans".

FONT_SIZE

Set this property equal to an integer specifying the font size for the grid labels and title (if present). The default value is 9 points for the grid labels and 11 points for the title.

FONT_STYLE

Set this property equal to an integer or a string specifying the font style for the title (if present). Allowed values are:

Integer	String	Resulting Style
0	"Normal" or "rm"	Default (roman)
1	"Bold" or "bf"	Bold
2	"Italic" or "it"	Italic
3	"Bold italic" or "bi"	Bold italic

LIMIT

Set this property to a four-element vector of the form

[Latmin, Lonmin, Latmax, Lonmax]

that specifies the boundaries of the region to be mapped. (Lonmin, Latmin) and (Lonmax, Latmax) are the longitudes and latitudes of two points diagonal from each other on the region's boundary.

Note: If the longitude range in LIMIT is less than or equal to 180 degrees, map clipping is performed in lat/lon coordinates before the transform. If the longitude range is greater than 180 degrees, map clipping is done in Cartesian coordinates after the transform. For non-cylindrical projections, clipping after the transformation to Cartesian coordinates means that some lat/lon points that fall outside the bounds specified by LIMIT may not be clipped. This occurs when the transformed lat/lon points fall inside the cartesian clipping rectangle.

Note: Lonmin should be in the range –180 to +180. Lonmax should be in the range –180 to +540, and must be greater than Lonmin. The total range for the map (Lonmax – Lonmin) must be 360 degrees or less.

Note: For the azimuthal projections (Azimuthal Equidistant, Lambert Azimuthal, Orthographic, Polyconic, and Stereographic), by default the map is clipped so that only one hemisphere is visible. For example, if you have set CENTER_LATITUDE=90 to display the Northern Hemisphere, then the limit will default to [0, -180, 90, 180]. To display regions outside of the default hemisphere, you should set the LIMIT property to your desired limits. For example, to display the Azimuthal Equidistant projection from 30°S to 90°N:

m = Map('Azimuthal Equidistant', CENTER_LATITUDE=90, LIMIT=[-30, -180, 90, 180])

mc = MapContinents(/FILL, TRANSPARENCY=50)

MAPGRID (Get only)

This property retrieves a reference to the existing MAPGRID object.

MAP_PROJECTION

A string giving the name of the current map projection. This is the same as the Projection argument. After creation, use this property to retrieve or set the current map projection.

NAME

A string that specifies the name of the graphic. The name can be used to retrieve the graphic using the brackets array notation. If NAME is not set then a default name is chosen based on the graphic type.

POSITION

Set this property to a four-element vector that determines the position of the graphic within the window. The coordinates [X₁, Y₁, X₂, Y₂] define the lower left and upper right corners of the graphic. Coordinates are expressed in normalized units ranging from 0.0 to 1.0. On creation, if the DEVICE keyword is set, the units are given in device units (pixels).

Note: After creation, you can set the POSITION to either a two or four-element vector. If two elements are provided, the center of the graphic will be translated to that position. If four elements are provided, the graphics will be translated and scaled to fit the position.

TITLE

Set this property to a string specifying a title. The title properties may be modified using FONT_COLOR, FONT_NAME, FONT_SIZE, and FONT_STYLE. After creation the TITLE property may be used to retrieve a reference to the title text object, and the TEXTproperties may be used to modify the title object.

You can add Greek letters and mathematical symbols using a TeX-like syntax, enclosed within a pair of "$" characters. See Adding Mathematical Symbols and Greek Letters to the Text String for details.

UVALUE

Set this property to an IDL variable of any data type.

WINDOW (Get Only)

This property retrieves a reference to the WINDOW object which contains the graphic.

WINDOW_TITLE

Set this property to the title of the IDL Graphic window. The title is displayed in the window's title bar.

XRANGE

A two-element vector giving the X data range to plot. The default behavior is to plot the entire data range.

YRANGE

A two-element vector giving the Y data range to plot. The default behavior is to plot the entire data range.

Version History

8.0	Introduced
8.1	Added the following properties: MAP_PROJECTION, MAPGRID, UVALUE, WINDOW. Added the following methods: Delete, MapForward, MapInverse.
8.2	Added BACKGROUND_COLOR, BACKGROUND_TRANSPARENCY, CLIP (Grid), LABEL_FORMAT (Grid) properties.
8.2.2	Change POSITION from a keyword to a property. Added Map Projection table.
8.6	Changed default font name and font size.
8.6.1	Added ellipsoid support to Near Side Perspective projection, added GOES-R map projection.

MAP

Example

Additional Examples

Syntax

Keywords

Properties

Methods

Return Value

Arguments

Projection

Map Properties

Map Grid Properties

Keywords

BUFFER

CURRENT

DEVICE

DIMENSIONS

LAYOUT

LOCATION

MARGIN

NO_TOOLBAR

NODATA

OVERPLOT

WIDGETS

Properties

BACKGROUND_COLOR

BACKGROUND_TRANSPARENCY

FONT_COLOR

FONT_NAME

FONT_SIZE

FONT_STYLE

LIMIT

MAPGRID (Get only)

MAP_PROJECTION

NAME

POSITION

TITLE

UVALUE

WINDOW (Get Only)

WINDOW_TITLE

XRANGE

YRANGE

Version History

See Also